PVCS adapter documentation

Feature overview
This version of the PVCS adaptor provides the following key features:

- Full access to all basic version control functions

- Version of files, History, Configurations, Branches

- Full support of PVCS configuration files (see PVCS and adapter configuration files for details)
- Support for PVCS keyword expansion
- Full support for the PVCS archive suffix rules
- Support for setting a version label to a single file or a group of files (including SNiFF+ change sets and floating labels)
- Possibilty to move a label from one revision to another revision for one file
- Automatic enabling/disabling of the PVCS custom menu in the SNiFF+ Project Editor (see Note about automatic PVCS custom menu for details)
- Automatic reread of the configuration files, if there is any change during runtime
- Possibility to run the PVCS command remotely on a UNIX box from a Windows NT machine.

Limitations and known issues of the current PVCS adapter
Comments and descriptions passed on to an archive during Checkin must not be seeded with quotes (single, double, backward,...)

The previous PVCS adapter used RCS type extensions for repository files, e.g. the file name had a

*.cpp,v type of extension. The current adapter uses a PVCS configuration file, where you can customize the used archive suffixes. The PVCS adaptor uses this configuration file as well to calculate the archive file extension. The archive suffix rules can be customized using the PVCS preferences dialog (see Using the PVCS preferences dialog for details).

Multiple PVCS archive suffix metarules (include a '?' inside the rule) are currently not supported, because PVCS seems to have a problem itself with multiple metarules. TakeFive will clear this issue as soon as possible.

The adaptor hasn't been currently tested on a Windows / Unix environment under cross plattform development circumstances.

PVCS access lists, access database and the promotion model is currently not supported by this version of the adaptor.

If the adaptor is used on a legacy repository, it can be, that the repository contains labels with a space character inside. This labels are not supported by SNiFF+. The adaptor replace the space character by a underscore (´_´) during reading the symbol list. Using the converted label name from inside SNiFF+ can lead to errors. Instead of using the symbol name directly, use the corresponding revision number to access the version of the label.

| Note
| Windows 95/98: If you want to use the PVCS integration on the operating systems Windows 95 or Windows 98 you must set the environment variable USERNAME . This variable must contain your login username, otherwise, there is no guarantee that the integration is working correctly.

The default behavior is that the adapter uses the default PVCS archive filename extensions (3rd position is replaced with a 'v' (.? = ??v___)). If you want to customize the extensions to the one you used directly with PVCS, resetup all archive suffix rules from PVCS in the PVCS Preferences Dialog under the tab sheet "Suffix Rules" (see Using the PVCS preferences dialog for details). The changes are immedetaly available.

| Note
| PVCS allows to specify suffix rules like '.cpp -> .cpp_v'. PVCS doesn't report any error or warning using this suffix rule, but the resulted archive is miscalculated (PVCS creates a archive extension '.cpp' instead the expected extension '.cpp_v'). To workaround this problem, use the suffix rule '.cpp -> +_v' instead.

Note about the remote calling possibilties inside the PVCS adapter:
The PVCS adapter uses a generic calling interface to the PVCS command line commands. Which real commands are used are defined in the two files 'PvcsLocal.py' and 'PvcsRemote.py'. Which interface is used will be controlled by the environment variable 'SNiFF_CMVC_USE_CALL_INTERFACE'. If this variable is set to the value '0', then the PVCS adapter uses the locally installed PVCS commands. If this variable has the value '1', then the PVCS adapter calls the PVCS commands remotely on another machine. The name of this machine is given by the environment variable 'PVCS_REMOTE_HOST'. To run the commands correctly on the remote machine, the adapter needs to know which Windows path correspond to which Unix path. This mapping has to be set in the Python dictionary 'PathMap' inside the file '

$SNIFF_DIR/lib/python/Sniff/Pvcs/PvcsRemote.py '.
For example:
PathMap = {
"G:":"/Project/Repository",
"H:":"/Project/WorkArea"
}
At least the drive letter including the colon has to be mapped to the correct corresponding Unix path. If the user name on the remote machine differs from the user name on your local machine, then set the correct remote user name using the environment variable 'SNiFF_CMVC_REMOTE_USER'.
Note about automatic PVCS custom menu

The current PVCS adapter version generates the necessary custom menu to access the dialogs for setting a version label and the PVCS preferences dialog automatically. By default, SNiFF+ looks for all enabled custom menus in the file

$SNIFF_DIR/config/
SiteMenus.sniff and merge these menus to the file $SNIFF_DIR/Profiles/$USERNAME/UserMenus.sniff (on Windows) or $HOME/.sniffrc/
UserMenus.sniff (on Unix) or if the environment variable $SNiFF_RESOURCE_DIR is set, to $SNiFF_RESOURCE_DIR/UserMenus.sniff . Already existing custom menus on a user level will not be deleted and not overwritten. As a last step, SNiFF+ copies the contents of the file $SNIFF_DIR/config/PvcsMenu.sniff to the end of the UserMenus file. The resulting menu looks like the following:

If you want to customize this menu, you should make the changes in the file

$SNIFF_DIR/config/PvcsMenu.sniff . Before restarting SNiFF+ to apply the changes, you MUST delete the old menu manually from the UserMenus file. In case you used custom menus before applying this version of the PVCS adapter, you should create a backup of your custom menus and you should check the correctness of your custom menus after the first start of SNiFF+ with this version of the adapter.

If you don't want to have the automatic merge at all or you want to merge it to the SiteMenus file, you can control the behavior of the automatic menu merge with setting two variables inside the responsible python file

$SNIFF_DIR/config/editor/
InitPVCSCustomMenu.py . The variable `forceUserLevel` (line 12 disable User- and enable SiteLevel; line 13 enable User- and disable SiteLevel) controls the destination of the custom menu. If `forceUserLevel` is set to "0", the custom menu will be written to the SiteMenus file. If `forceUserLevel` is set to "1", the custom menu will be written to UserMenus file (this is the default). If you want to switch off the automatic merge of the custom menu, then set the variable `enableAutoMenu` to "0" (line 16). Only if the variable `enableAutoMenu` is set to "1" (line 17, this is the default) the python script will try to merge the menus.

The generated custom menu contains the following actions:

- Set Label on Revision...

- Calls the set label dialog and provides the possibility to set a fixed or a floating label and a fixed or a floating SNiFF+ changeset. See Using the Set Label on Revision dialog for further details

- Move Label to...

- Moves a selected label in the history pane of the project editor to a new revision. If there is more than one label assigned to the correspondig revision, select the correct label in the upcoming dialog. Floating labels or changesets become fixed after a move operation

- Preferences...

- Opens the PVCS integration preferences dialog. See Using the PVCS preferences dialog for further details.

Setting up projects with SNiFF+ and PVCS
If you want to create a new project, choose Project > New Project... > With defaults... from SNiFF+'s Launch Pad. Switch to the Version Control System node of the Project Attributes Dialog and select PVCS as VCS Tool.

If you want to create a PVCS repository for an already existing SNiFF+ project, or if you want to set up a SNiFF+ project for an already existing PVCS repository, from SNiFF+'s Project Editor, choose Project > Attributes of Project projectname. In the Project Attributes dialog, switch to the Version Control System node and select PVCS as VCS Tool. Now you have full access control of a PVCS repository from within SNiFF+. For instance, if you want to check in and check out files, or if you want to create a new branch version, just choose the right menus from SNiFF+.

The PVCS adapter has all version control features for which SNiFF+ provides an interface, e.g. all Configuration Manager menus (see Feature overview for more details). Furthermore, the adapter can also deal with all repository actions related to SNiFF+'s working environment concept. For further details about working environments, please refer to the SNiFF+ User's Guide.

Sometimes, however, you might want to use the graphical user frontend of PVCS together with SNiFF+, e.g. because you slowly want to migrate to the fully integrated development approach pursued by SNiFF+. In this case, you can extend the custom menu (file

$SNIFF_DIR/config/PvcsMenu.sniff ) and call PVCS commands or the PVCS graphical interface from SNiFF+. For further details on custom menus, please refer to the SNiFF+ Reference Guide. We recommend, that you use the PVCS graphical user frontend only to check the correctness of the integration with SNiFF+ and for customizing the used PVCS master and/or project configuration file.

| Note
| Changes to the archive suffix rules should be done by using the PVCS preferences dialog which is supplied together with this version of the adapter. Otherwise, we can't make any guarantees for the correct handling of the archive suffix rules in all cases.

PVCS and adapter configuration files
PVCS uses configuration files to store all settings used to control the behavior of the PVCS commands. Multiple levels of configuration files are possible with PVCS up to the depth of 20. If you are using the graphical user interface of PVCS, you can set at least a master configuration file and a project configuration file. By default, PVCS only uses the master configuration file. If you have changed the configuration file setting for one PVCS project, this is your project configuration file. The PVCS adapter of SNiFF+ can handle multiple levels of configuration files as well and you can set an additional master configuration file and an additional project configuration file using the PVCS preferences dialog supplied with this version of the adapter. The PVCS adapter uses a fixed file to store all configuration setting necessary for SNiFF+:

$SNIFF_DIR/lib/python/Sniff/Pvcs/Pvcs4Sniff.cfg
This is the master configuration file of the PVCS adapter. These file contain all settings necessary for SNiFF+ and at least the default archive suffix rule ".? = ??v___".

| Note
| All archive suffix rules all archive suffix rules will be stored in this file if you are using the PVCS preferences dialog. That means, this file must be writeable for all users which should have the permission to change the archive suffix rules.

The configuration files will be read in the following order:

- the default PVCS master configuration file (only PVCS 6.0)
- all included configuration files
- the SNiFF+ master configuration file

The settings in these configuration files will be merged in an incremental process. That means, that a setting which is only present in the master configuration file will be applied as well as a setting in the SNiFF+ master configuration file. For all settings which are in more than one configuration file, only the setting in the last configuration file will be used. In this case, the SNiFF+ master configuration file is the last instance for configuration settings. The settings in the following chapter shouldn't be changed or overwritten. The correct behavior of the adapter is only guaranteed with at least these settings.
Non Default Settings in the Configuration File
The following settings overwrite the default settings of PVCS:

- QUIET | ... display only minimal messages
- NOSIGNON | ... no copyright message of PVCS
- NOMULTILOCK | ... NOMULTILOCK REVISION or USER is the default PVCS setting, Checkin with Concurrent Lock will set 'MULTILOCK REVISION
- IGNOREPATH | ... use VCSDIR to specify repository directory
- NODELETEWORK WRITEPROTECT | ... check in doesn't remove the workfiles
- EXPANDKEYWORDS TOUCH | ... keyword expansion change the timestamp of the workfile
- LOGIN HOST, VCSID, UNKNOWN | ... use the login sources HOST, VCSID and 'No Source' (UNKNOWN)
- NOSHARE | ... set exclusive use of archives for all operations
- DATEFORMAT | ... set DATEFORMAT SNiFF+ Configuration Manager compatible (yyyy/mm/ddd hh:mm:ss)

All other configuration settings can be overwritten or deleted from the SNiFF+ configuration file if you are using the additional master and/or project configuration files. Otherwise deletion of configuration settings can disable some functionality.